Skip to content

docs: allow multiple passkey credentials#479

Open
DhruvPareek wants to merge 1 commit into
docs-auth-signed-retry-examplesfrom
dp/grid-multiple-passkey-auth-docs
Open

docs: allow multiple passkey credentials#479
DhruvPareek wants to merge 1 commit into
docs-auth-signed-retry-examplesfrom
dp/grid-multiple-passkey-auth-docs

Conversation

@DhruvPareek
Copy link
Copy Markdown
Contributor

@DhruvPareek DhruvPareek commented May 19, 2026

Summary

  • Document one EMAIL_OTP credential and multiple distinct PASSKEY credentials.
  • Update duplicate passkey error docs to refer to duplicate WebAuthn credentialId.
  • Update Global Accounts authentication docs to recommend passkeys as backup credentials.
  • Rebuild bundled OpenAPI specs.

Test Plan

  • make build
  • npm run lint
  • git diff --check

@vercel
Copy link
Copy Markdown

vercel Bot commented May 19, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
grid-flow-builder Ready Ready Preview, Comment May 19, 2026 8:38pm

Request Review

@mintlify
Copy link
Copy Markdown
Contributor

mintlify Bot commented May 19, 2026

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
Grid 🟢 Ready View Preview May 19, 2026, 7:17 PM

@DhruvPareek DhruvPareek marked this pull request as ready for review May 19, 2026 19:16
Copy link
Copy Markdown
Contributor Author

DhruvPareek commented May 19, 2026

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 19, 2026

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

csharp

docs(api): clarify multiple PASSKEY credentials allowed in credential creation

go

docs(api): clarify multiple passkeys supported in authcredential

kotlin

docs(api): clarify multiple passkey support in auth credentials create

openapi

docs(api): clarify multiple passkey support in auth credentials

php

docs(api): update passkey credential limit documentation in auth credentials

python

docs(api): clarify multiple passkey support in auth credentials

ruby

docs(api): clarify multiple passkey credentials supported in auth

typescript

docs(api): clarify passkey credential limits in auth.credentials

Edit this comment to update them. They will appear in their respective SDK's changelogs.

grid-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

grid-ruby studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️build ⏭️lint ⏭️ (prev: lint ❗) → test ⏭️ (prev: test ✅)

grid-go studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗build ⏭️lint ⏭️ (prev: lint ❗) → test ⏭️ (prev: test ❗)

go get github.com/stainless-sdks/grid-go@85ae1dbcc234e2da2389f67fd2b1c5c61ca4b085
grid-kotlin studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ⏭️ (prev: test ❗)

grid-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ⏭️lint ⏭️test ⏭️ (prev: test ✅)

grid-csharp studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗build ⏭️ (prev: build ❗) → lint ⏭️ (prev: lint ❗) → test ⏭️ (prev: test ❗)

grid-php studio · code · diff

Your SDK build had at least one "error" diagnostic, but this did not represent a regression.
generate ❗lint ⏭️ (prev: lint ✅) → test ⏭️ (prev: test ✅)

grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️build ⏭️ (prev: build ❗) → lint ⏭️ (prev: lint ❗) → test ⏭️ (prev: test ❗)

grid-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅build ⏭️lint ⏭️test ⏭️ (prev: test ❗)


This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-05-19 20:40:18 UTC

@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented May 19, 2026

Greptile Summary

This PR updates the authentication credential documentation to reflect that multiple distinct PASSKEY credentials (differentiated by WebAuthn credentialId) are now allowed per internal account, while the one-per-account limit for EMAIL_OTP remains. Error descriptions and user-facing guidance are updated consistently across both source and bundled OpenAPI specs.

  • Credential limits clarified: PASSKEY_CREDENTIAL_ALREADY_EXISTS now correctly scopes the uniqueness constraint to the WebAuthn credentialId rather than credential type, and the endpoint description, 400 response prose, inline note, and the global-accounts MDX snippet are all updated in sync.
  • Backup credential guidance updated: The "Managing credentials" section now recommends adding another passkey (or an email OTP) as a backup, which aligns with the relaxed passkey limit.
  • Bundled specs regenerated: openapi.yaml and mintlify/openapi.yaml are rebuilt via make build and match the source changes exactly.

Confidence Score: 5/5

Documentation-only change with no application logic; all updated descriptions are consistent across source and bundled files.

All five changed files are documentation or generated spec bundles. The credential-limit semantics are updated consistently in the source YAML, the bundled root spec, the Mintlify bundle, and the MDX snippet. No logic, migrations, or API behaviour is altered.

No files require special attention.

Important Files Changed

Filename Overview
openapi/paths/auth/auth_credentials.yaml Endpoint description updated to allow multiple distinct PASSKEY credentials; 400 response description updated to clarify per-credentialId uniqueness constraint.
openapi/components/schemas/errors/Error400.yaml Updated PASSKEY_CREDENTIAL_ALREADY_EXISTS description to reflect WebAuthn credentialId-scoped uniqueness; EMAIL_OTP entry unchanged.
mintlify/snippets/global-accounts/authentication.mdx Updated credential multiplicity docs: one EMAIL_OTP, multiple distinct PASSKEYs, OAUTH per provider; backup credential guidance now recommends adding a second passkey.
openapi.yaml Bundled root spec regenerated from source; changes are identical to source files.
mintlify/openapi.yaml Bundled Mintlify spec regenerated from source; changes are identical to source files.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[POST /auth/credentials] --> B{Credential type?}
    B --> |EMAIL_OTP| C{EMAIL_OTP already exists?}
    B --> |PASSKEY| D{Same WebAuthn credentialId already registered?}
    B --> |OAUTH| E[Add credential for provider identity]
    C --> |Yes| F[400 EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS]
    C --> |No| G[202 → signed retry → 201 Created]
    D --> |Yes| H[400 PASSKEY_CREDENTIAL_ALREADY_EXISTS]
    D --> |No| I[202 → signed retry → 201 Created - Multiple distinct PASSKEYs allowed]
    E --> J[202 → signed retry → 201 Created]
Loading

Reviews (4): Last reviewed commit: "docs: allow multiple passkey credentials" | Re-trigger Greptile

| **`EMAIL_OTP`** | Lowest-friction option. Works on any device with email access — no biometric hardware, identity provider, or client SDK required beyond the code entry field. |

A single internal account can hold one credential of each type concurrently. Only one `PASSKEY` and one `EMAIL_OTP` per account in v1.
A single internal account can hold one `EMAIL_OTP` credential and multiple distinct `PASSKEY` credentials concurrently. `OAUTH` credentials can be added for each supported provider identity.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Unverified OAUTH multiplicity claim

The new sentence — "OAUTH credentials can be added for each supported provider identity" — is a behavioral assertion that isn't corroborated by any change in the API error codes or the OpenAPI spec. The old text implied one credential of each type; this PR only updates the PASSKEY constraint with a matching PASSKEY_CREDENTIAL_ALREADY_EXISTS clarification. If the OAUTH limit is also provider-scoped (i.e., one per provider rather than one total), there should be a corresponding error-code description (or at least a note in the API spec) backing this claim. Without it, a developer who tries to register a second OAUTH credential and hits an undocumented error will be confused by the mismatch between docs and API behavior.

Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/global-accounts/authentication.mdx
Line: 9

Comment:
**Unverified OAUTH multiplicity claim**

The new sentence — "OAUTH credentials can be added for each supported provider identity" — is a behavioral assertion that isn't corroborated by any change in the API error codes or the OpenAPI spec. The old text implied one credential of each type; this PR only updates the PASSKEY constraint with a matching `PASSKEY_CREDENTIAL_ALREADY_EXISTS` clarification. If the OAUTH limit is also provider-scoped (i.e., one per provider rather than one total), there should be a corresponding error-code description (or at least a note in the API spec) backing this claim. Without it, a developer who tries to register a second OAUTH credential and hits an undocumented error will be confused by the mismatch between docs and API behavior.

How can I resolve this? If you propose a fix, please make it concise.

Fix in Claude Code

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new sentence is true

Comment thread openapi/components/schemas/errors/Error400.yaml
@DhruvPareek DhruvPareek marked this pull request as ready for review May 19, 2026 19:25
@DhruvPareek DhruvPareek requested a review from pengying May 19, 2026 19:25
@DhruvPareek DhruvPareek changed the base branch from main to graphite-base/479 May 19, 2026 19:45
@DhruvPareek DhruvPareek force-pushed the dp/grid-multiple-passkey-auth-docs branch from 399d0f1 to e08f4d3 Compare May 19, 2026 19:46
@DhruvPareek DhruvPareek changed the base branch from graphite-base/479 to docs-auth-signed-retry-examples May 19, 2026 19:46
@DhruvPareek DhruvPareek marked this pull request as draft May 19, 2026 20:25
@DhruvPareek DhruvPareek removed the request for review from pengying May 19, 2026 20:25
@DhruvPareek DhruvPareek marked this pull request as ready for review May 19, 2026 20:28
@DhruvPareek DhruvPareek marked this pull request as draft May 19, 2026 20:29
Summary:

- Update auth credential OpenAPI source to describe one EMAIL_OTP credential and multiple distinct PASSKEY credentials.
- Update PASSKEY_CREDENTIAL_ALREADY_EXISTS docs to mean duplicate WebAuthn credentialId rather than one-passkey-per-account.
- Update Global Accounts authentication docs to recommend backup credentials including additional passkeys.
- Rebuild bundled openapi.yaml and mintlify/openapi.yaml.

Test Plan:

- make build
- make lint
- git diff --check
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants